\chapter{Scene Description Language}

SimSpark provides access to the managed scene graph in several ways.
Besides the internal C++ interface and external access via Ruby script
language, an extensible mechanism for scene description languages is
implemented. This allows for both a procedural and a description-based
scene setup.

A scene is imported using one of any number of registered scene
importer plugins, each supporting a different scene description
language.

\section{RubySceneGraph language}

Currently one S-expression-based importer is implemented. This
language is called \emph{RubySceneGraph} (RSG for short) and used to
model the current robot models. It maps the scene graph structure to
the nesting of Lisp-like \texttt{s-expressions}.

An s-expression is a list of elements. Each element is either an
\texttt{atom} or is itself another \texttt{list} of atoms. An atom is
either a predefined keyword or a non empty string literal that has no
further syntactic structure. The syntax of s-expressions, written
using EBNF is given in Listing~\ref{rsg:ebnf}.

\lstset{captionpos=b,frame=none,%
  basicstyle=\small,breaklines=true}

\begin{lstlisting}[caption={EBNF notation of s-expressions}, label=rsg:ebnf]
character    -> "A" | ... | "Z" | "1" | ... | "9",
atom         -> character+
list         -> "(" s_expression* ")"
s_expression -> atom | list
\end{lstlisting}

%xleftmargin=1cm,xrightmargin=1cm
\lstset{language=lisp,language=lisp,captionpos=b,frame=none,%
  basicstyle=\small,commentstyle=\bf,breaklines=true}

On the semantic side the \emph{RubySceneGraph} interpreter recognizes
a set of special atoms. The first atom in each subexpression
determines its type. The set of keywords comprises some atoms that
allow the interpreter to distinguish different expression types.

For most expression types exists a short hand notation that can be
used to save some typing. The short hand notation is further used in
the monitor protocol to keep it more compact.

\begin{itemize}
  
\item The \texttt{RubySceneGraph} expression is the header expression
  of every scene graph file.

\item The \texttt{node} (short \texttt{nd}) expression declares a new scene graph node.  

\item The \texttt{importScene} expression is replaced with the content
  of another scene graph file.
  
\item The \texttt{template} (short \texttt{templ}) expression declares a set of parameters
  for a following scene fragment that can later be reused like a
  macro.

\item The \texttt{define} (short \texttt{def}) expression defines a variable with the scope 
  of the current scene file and all files sourced with the
  \texttt{importScene} expression.

\item The \texttt{eval} 
expression uses the ruby interpreter to evaluate an expresion and is
replaced by the computed value.
 
\item Every other expression type is interpreted as a \texttt{method
    call} that is carried out by the ruby Script interface

\end{itemize}

Apart from the different expression types listed above a replacement
mechanism is implemented. Every atom literal starting with a dollar
sign is interpreted as a template or variable parameter and replaced
with its actual value.

We shall describe the semantic of the different expression types below
together with some small usage examples and a partial reference of
available node types and methods.

\section{File structure}

The top level structure of a ruby scene file consists of two
s-expressions. The first expression must be the header expression. It
allows the parser to confirm the file type and to get information
about the version of the used language.

The syntax of the header expression is \texttt{(RubySceneGraph <major
  Version> <minor Version>)}. Currently the only valid header states
\texttt{0} for the major and \texttt{1} for the minor version.

The header is followed by a single s-expression that contains the
scene graph body. Any further expression is discarded. The body
expression consists of an optional single template expression and a
set of node expressions. The resulting structure is outlined in
listing~\ref{rsg:structure}. Note that lines starting with a semicolon
are comment lines.

\begin{lstlisting}[caption={File Structure},label=rsg:structure]
; the header expression
(RubySceneGraph 0 1)
(
 ; the body of the file starts here

 ; declare this file as a template
 (template \$lenX \$lenY \$lenZ \$density \$material)

 ; compute the volume of the box
 (define \$volume eval (\$lenX * \$lenY * \$lenZ)

 ; declare the top level scene graph node
 (node Box
       ; children of the top level node go here
       (node DragController
       )
 )
)

\end{lstlisting}

\section{Node Expression}

The scene graph consists of a tree of object instances, called nodes.
Each node in the scene graph is declared with the \texttt{(node
<ClassName>)} expression. The \emph{ClassName} argument gives the name
of a class registered to the Zeitgeist class factory system.

The semantic of a node expression is to instantiate a new scene graph
object of the given class type. The importer therefore relies on the
Zeitgeist class factory system to create the requested object. It is
then installed as a child of the nearest enclosing node expression. If
there is no enclosing node expression then the node is a top level
node of the expressed scene graph.

The set of top level nodes are installed as children of the node below
which the current graph is imported. This is either the global root
node of the system, or an insertion point defined with the importScene
expression within another scene graph file. The nesting of node
expressions therefore defines directly the structure of the resulting
scene graph with a very small syntactic overhead.

The set of top level nodes are installed as children of the node below
which the current graph is imported. This is either the global root
node of the system, or an insertion point defined with the importScene
expression within another scene graph file. The nesting of node
expressions therefore defines directly the structure of the resulting
scene graph with a very small syntactic overhead.

\section{Scene Graph templates}
\label{subsec:template}

The language further allows the reuse of scene graph parts in a macro
like fashion. This enables the construction of a repository of
predefined partial scenes, or complete agent descriptions. The macro
concept is available through the \texttt{(importScene <filename>
<parameter>*)} expression. This expression recursively calls the
importer facilities of the system. It takes the nearest enclosing node
expression as the relative root node to install the scene graph
described within the given file.

Note that the given file must not necessarily be another
RubySceneGraph file but any file type registered to the importer
framework. This allows the nesting of scene graph parts expressed in
different graph description languages. An example application of this
feature is that parts of the resulting scene could be created by
application programs better suited to create 3D models. By now, we do
not exploit this feature yet.

The list of parameters given to the importScene expression is passed
on to the responsible importer plugin. If another ruby scene graph
file is imported that declares a template, they are substituted with
its formal parameters.

A template declaration within the imported file has to meet the
following syntax: \texttt{(template <parameterName>*)}. A parameter
name is a string literal that is prefixed with a dollar sign, see
listing~\ref{rsg:structure} for an example declaration. All parameter
names that follow within the body of the file are replaced with their
actual content.

The usage example in listing~\ref{rsg:import} below assumes a
\texttt{box.rsg} file. It uses that to construct boxes with varying
sizes and colors.

\begin{lstlisting}[caption={importScene example}, label=rsg:import]
(RubySceneGraph 0 1)
(
 (node Transform 
       (importScene box.rsg 1 3 0.8 10 matRed)
 )
 (node Transform
       (importScene box.rsg 2 4 0.4 8 matBlue)
 )
)
\end{lstlisting}


\section{Language Reference}
 
% language reference (i.e. class and method names) overlap with the class reference.
% maybe we should provide one common class reference that marks the methods available to ruby?

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "user-manual"
%%% End: 
